Creating a Step Control Using a ViewBox

IN THIS PAGE

Defining the ViewBox
Adding Buttons to Step Through the ViewBox Array
Setting the Step by Entering a Value
Creating a Text Area that Defines Steps
Tying the Values of the Step Array to Different Panels

Description

When completing an order online, filling out educational information, taking an online test, or checking the status of a parcel in the post, it is common to see a stepped bar showing the current progress towards the completion of the item in question. This 'step control' is relatively easy to define using a ViewBox. It can then be tied to the panels in a panel navigator.

Step controls are used frequently to indicate progress.

Defining the ViewBox

In the UX Builder on the UX Controls page open the 'Data Controls' menu. Click on the [ViewBox] option to add a viewbox control to your component. Give the viewbox the name 'step'.
Highlight the viewbox control in the controls tree. In the properties list on the right click the button next to the 'ViewBox properties' property, in the 'ViewBox Properties' section.
In the ViewBox Builder open the 'Data Source' pane. Click the button next to the 'ViewBox type' property and select 'Data'.
Click the dropdown next to the 'Datasource type' property and select 'Static JSON'.
Click the button next to the 'Static JSON' property.
Define the following array of JSON Data. These represent the default steps in the step control. Click OK.
```
[
'One',
'Two',
'Three',
'Four'
]
```
Open the 'ViewBox Properties' pane. In the 'ViewBox Properties' section check the 'Auto-refresh when ViewBox value changes' checkbox.
Any time the viewbox changes a refresh is needed due to the fact that the value of the viewbox is being displayed.
Check the 'Allow any value' checkbox, also in the 'ViewBox Properties' section.
This property needs to be checked because the values in this viewbox are not set values. However, there are default values.
Open the 'ViewBox Layout' pane and select the 'Freeform editor' radio button.
Define the following template.
```
{*root}
<div class="step {*if [temp].value >= [count] || [count] == 0}stepDone{*endif}" style="width: {100/[root].length}%;">
{[value]}<div class="stepBar"></div><div class="stepDot"></div></div>
{/*root}
```
The {*root} tag is used around data that contains a JSON array. This tag allows you to add headers and footers to a template. This template has a main <div> tag that contains an 'if' statement. The logic of this statement is this; if the value of the viewbox is greater than the item that is being iterated over add the CSS class 'stepDone'. The 'style' definition in this <div> sets the width as an expression that sets the size of each step as a percentage. The percentage allotted each step is determined by dividing the number of steps by 100. This is accomplished by getting the length of the array using '[root].length'. Inside the main <div> there are two additional <div> tags, one pointing to the CSS class 'stepBar' and the other 'stepDot'. This allows for the relative positioning of the points along the step control.

Open the 'CSS' pane and add the following CSS classes. Click OK.

.step {
position: relative;
display: inline-block;
text-align: center;
padding-bottom: 14px;
}

.stepBar {
position: absolute;
height: 4px;
background: #ddd;
border-radius: 2px;
width: 100%;
left: -50%;
bottom: 3px;
z-index: 4;
}
.stepDot {
position: absolute;
height: 10px;
width: 10px;
background: #ddd;
border-radius: 5px;
left: 50%;
bottom: 0px;
margin-left: -5px;
z-index: 5;
}
.stepDone .stepBar, .stepDone .stepDot {
background:#007cdb;
}
.step:first-child .stepBar, .stepDone:first-child .stepBar {
background: transparent;
width: 50%;
left: 0px;
}

'stepBar' is a section of the step control and 'stepDot' is a point on this bar. 'stepDot' makes a dot at the center of each step. 'stepDone' changes the background color when a step is complete. The last selector in the CSS pane is there to make sure that the first step is not shown.

Adding Buttons to Step Through the ViewBox Array

In the UX Builder on the UX Controls page open the 'Other Controls' menu. Click on the [Button] option to add a button control underneath the ViewBox.
Highlight the button control. In the properties list on the right set the 'Button text' property to read 'Previous'.
Scroll down the properties list to the 'Javascript - (Touch, Mouse, Pointer Events)' section. Click the button next to the 'click' property.

In the 'Edit Click Event' dialog select the 'Text mode' radio button and add the following javascript, then click Save.

var val = {dialog.object}.getValue('step');
val = Number(val)-1;
if(val < 0) val = 0;
{dialog.object}.setValue('step',val);

With the 'Previous' button highlighted in the controls tree click the 'Toggle break' icon in the UX Controls toolbar to turn off the break.
Click on the [Button] option in the Other Controls menu again to add a second button underneath the first.
Highlight the new button. In the properties list on the right change the 'Button text' property to read 'Next'.
Scroll down again to the 'Javascript - (Touch, Mouse, Pointer Events) section. Click the button next to the 'click' property.
In the radio button menu select 'Text mode'. Add the following Javascript definition for the click event and hit 'Save'.
```
var val = {dialog.object}.getValue('step');
val = Number(val)+1;
{dialog.object}.setValue('step',val);
```
Run the component in Live Preview. Click on the Previous and Next buttons. You should see a blue progress bar move back and forth between the steps.

Setting the Step by Entering a Value

Return to the UX Builder's Design tab. On the UX Controls page open the 'Data Controls' menu and click on [TextBox] to add a textbox control to the component. Give this control the name and label 'val'.
Open the 'Other Controls' menu. Click on the [Button] option to add a button control to the UX component.
Highlight the button. In the properties list on the right change the 'Button text' property to read 'Set Step'.
Scroll down to the 'Javascript - (Touch, Mouse, Pointer Events)' section of the properties list. Click the button next to the 'click' property.
In the 'Edit Click Event' dialog select the 'Text mode' radio button. Enter the following Javascript definition to the click event and hit the 'Save' button to exit.
```
{dialog.object}.setValue('step',{dialog.object}.getValue('val'));
```
Enter a number value from the step control into the textbox control and click the 'Set Step' button. You should see the progress bar jump to that element in the array.
Javascript arrays are zero based so entering 1 will jump to the second dot.

Creating a Text Area that Defines Steps

On the UX Controls page open the 'Data Controls' menu. Click on [TextArea] to add a text area control to the component. Give the control the name 'pop' and the label 'Step List'.
Open the 'Other Controls' menu. Click on the [Button] option to add a button control.
Highlight the new button. In the properties list on the right set the 'Button text' property to read 'Populate'.
Scroll down to the 'Javascript - (Touch, Mouse, Pointer-Events)' section. Click the button next to the 'click' property.
In the 'Edit Click Event' dialog select the 'Text mode' radio button. Add the following Javascript to the click event definition and hit 'Save'.
```
var vals = {dialog.object}.getValue('pop');
vals = vals.split('\n');
var vb = {dialog.object}.getControl('step');
vb.populate(vals);
```
Run the Component in Live Preview. Enter a list of items in the text area with each item separated by a carriage return. Click the populate button. The Step control should create steps from the items on the list.

Tying the Values of the Step Array to Different Panels

You can tie the values in the step array to panels, such that any information to be entered or displayed in each step is contained within a Panel inside a Panel Navigator. One simple way to accomplish this is to assign the Previous and Next button properties on a Panel Navigator to the Previous and Next buttons used in the Step Control. The guide for the 'Previous Card Button ID' demonstrates how this can be achieved. In this case the size of the static JSON array in the step control should correspond to the number of panels being clicked through.

Report an issue with this page